Getting Started with Win32 GrADS

Version 1.7.Beta.9

Contents

• Introduction
• System Requirements
• This Distribution
• X Server Setup
• Using Win32 GrADS
• Documentation
• Using GrADS with Athena Widgets
• Writing GIF and other image formats from GrADS
• Bugs
• Acknowledgements
• Getting Help

Introduction

Win32 GrADS is a port of Brian Doty's popular Grid Analysis and Display System (GrADS) to the x86 PC running 32-bit MS Windows operating sytems (win95 and winNT).

This implementation of Win32 GrADS is functionally equivalent to all Unix versions. Supported features include:

• Command line editing ("readline")
• Animation, mouse and X Window widgets
• Scriptable Graphical User Interface (GUI) with Athena widget support
• Input of binary IEEE, GRIB and self-describing NetCDF/HDF-SDS files conforming to the COARDS conventions, and eXternally defined NetCDF-SDS files which do not conform to the COARDS conventions
• Output of GRIB and NetCDF/HDF-SDS files through an interface to PCMDI's LATS library
• Direct output of GIF, JPEG, BMP and many other image formats through an interface to the ImageMagick library. This is an experimental feature: both syntax and functionality may change in future releases.

System Requirements

Win32 GrADS is a 32-bit application. You must have the following hardware/software:

• 80486 processor (Pentium or higher recommended)
• Windows 95 or Windows NT 4.0
• 16 megabytes memory (RAM)
• 12 megabytes hard disk space for full installation, 6 megabytes of hard disk space for compact installation.
• X server (see below)

This Distribution

In this installation you will find the following sub-directories:

• win32/ - GrADS, utilities and required dynamic linked libraries (DLLs)
• dat/ - map data bases and GrADS fonts
• lib/ - several GrADS scripts of interest
• doc/ - GrADS manual (MS Word format and HTML), reference cards (postscript), and assorted Unix style manual pages (converted to HTML).

Sample data files are not included in this distribution; a small collection of sample gridded and station data files can be downloaded from ftp://sprite.llnl.gov/pub/fiorino/grads/data/. The GrADS binaries and executables in win32/ as well the documentation files under doc/ are further described below. We start with the necessary X Server setup.

X Server Setup

Because Win32 GrADS is based on the same code as the Unix version, it requires an X server. An X server is the software which processes instructions from "X clients" such as GrADS to do things like draw on the screen. Win32 GrADS X has worked with a wide variety of X servers including a free one which is available from Micro Images at:

http://www.microimages.com/www/html/freestuf/mix.htm

This server is somewhat limited as it does not fully support the Athena widgets (only an issue if you intend to use GradsGUI - read on). There is a fully functional demo (2 hour limit) from Starnet which is somewhat nicer:

http://www.starnet.com/docs/xwin32.html

Win32 GrADS works quite nicely with this X server. For information on setting up X-Win32 to work with GrADS click here.

For a comprehensive list of other commercially available X servers consult Kenton Lee's page:

http://www.rahul.net/kenton/xsites.html

Before proceeding, choose an X Server and install it on your machine.

Using Win32 GrADS

Now that you have installed your X Server you are ready to go. Start your X server, and from the Start menu, click on Programs, and then click on Win32 GrADS. If you are new to GrADS you may want to start with the GrADS Tutorial.

Very Important: You must start your X server before running GrADS, it is not enough to install it.

During SETUP the user can choose between a Typical (full) and a Compact installation. Depending on the Installation Option you chose, you will find the following applications in the Win32 Program Group:

You can also start Win32 GrADS or any of the applications above from the DOS command line, e.g.,

c:\> grads

Recall that DOS is case insensitive, so grads is the same as GrADS.

Documentation

The sub-directory doc/ contains several documentation files of interest. Please notice that some of the documentation is out of date (the manual is for version 1.5 and the Unix manual pages for version 1.6). They have been included here under the assumption that out of date documentation is better than no documentation at all. These files will be updated as revised versions become available.

Using GrADS with Athena Widgets

Starting with version 1.7, GrADS provides a simpler way for creating widgets (graphical user interface) from a user defined GUI script. A GUI script included in this distribution alllows you to build the following user Graphical User Interface for GrADS:

For additonal information consult the document Using GrADS with Athena Widgets.

Notes:

1. If you are familiar with X11 widgets build with "gs" scripts, note that this is a completely different set of functions for building event driven widgets. Currently, there is a separate script processor (the gui command available from the ga-> prompt) for handling these functions. The Win32 application GradsGUI automatically starts a GUi script for you; try it!
2. This is an experimental version: both the scripting language as well as the available callbacks may change in the near future.
3. Although it does not crash the free X server from Micro Images, the menu items become invisible when you try to select it (this is due to a bug in the MI/X server). This feature works much better with the X-Win32 server from StarNet.
4. You can also add a graphical user interface (GUI) to GrADS by using the XGrads package based on tcl/tk. This package has been shown to run on Win32. For more information, take a look at:

ftp://sprite.llnl.gov/pub/fiorino/grads/XGrads/xgrads.win32.tar

Writing GIF and other image formats from GrADS

Starting with version 1.7.beta.7, the command wi (write image) saves the contents of the GrADS graphics screen directly to an image file. There is no need for writing a GrADS metafile or doing conversions to GIF or to other format, the output is already in the desired format. This feature is implemented in Win32 GrADS by means of an interface to the ImageMagick library, and it does not work in batch mode (-b option). Notice that this is an experimental command: both syntax and functionality may change in future releases.

To try it out, display something on the graphics screen, say, run rgbmap, and at the ga-> prompt enter

wi test.gif for writing a GIF file
wi test.jpeg for writing a JPEG file
wi test.bmp for writing a Windows BMP file
etc.

The general syntax for the wi command is:

wi fname.fmt

where fname is a generic file name, and fmt is one of the ImageMagick supported formats: gif, bmp, cgm, eps, fax, ico, jpeg, pcx, hdf, and many more.

Notes

1. The related command outxwd produces an xwd (X window dump) image file, being equivalent to wi fname.xwd. Noticed that outxwd currently now works with Win32 GrADS.
2. If a file name extension is not specified, GIF is the default.
3. Some ImageMagick formats (tiff, png, mpeg, ...) are not yet supported by Win32 GrADS.
4. Make sure no other window is on top of your GrADS graphics windows when issuing a wi command, as wi takes a snapshot of the current state of this window. For example, if a text editor window is partially covering your graphics window, your image file will contain the combination of these 2 windows.
5. If a format is not recognized (or supported), the image will be saved in MIFF, ImageMagick's native format.
6. See Bugs for problems on systems with more than 256 colors.

Bugs

On some systems the following problems have been reported:

1. On Windows 95 systems, GradsHDF, the version built with the NCSA MFHDF library has a subtle bug when reading certain 16-bit (short) packed NetCDF files (examples are NCEP re-analysis files converted to NetCDF at CIRES/CDC). Although GrADS is able to produce a plot, it mistankenly produces very large values for a hand full of grid points. Work around: use GradsNC in such cases. This problem has not been reported on Windows NT systems.
2. X Windows widgets built with gs scripts may miss/delay some X events (keyboard/mouse clicks). This problem appears to occur only on Windows 95; it has not been reported on Windows NT.
3. Athena widgets built with gui scripts: menu items become invisible when selected (MI/X Server only); some mouse delays on Windows 95.
4. The wi command has been reported to produce black and white GIF output on VGA systems with more than 256 colors. The workaround is to write a JPEG image, or to change your Windows display to 256 colors.

Acknowledgements

This Win32 port was contributed by Arlindo da Silva from the Data Assimilation Office (NASA/GSFC), in collaboration with Mike Fiorino from PCMDI/Lawrence Livermore National Laboratory. Win32 GrADS is built with the Cygnus GNU Win32 compiler. Sergey Okhapkin ported X11R6.3 to GNU Win32. The wi command is implemented through an interface to ImageMagick API; ImageMagick is written by John Cristy. Don Hooper helped porting the SDF interface; Steve Emmerson provided guidance with UDUNITS. Brian Doty tested some of the grads widget features. Many thanks to all.

GrADS User Group List Server

This server is used for the exchange of information on GrADS, announcements of upgrades, scripts, user defined functions, problem solving, etc. To subscribe, send mail to Sanzio Bassini (bassini@cineca.it) requesting inclusion in the GrADS User Group mailing list. Make sure to include your full name, affiliation and e-mail address.

An online archive for the listserver is maintained at:

• http://hera.gsfc.nasa.gov/grads_listserv/

Office Head: Ricky Rood
Page Author: Arlindo da Silva